chore(docs): deprecation notices for methods and properties #15394

petebacondarwin · 2016-11-15T16:15:15Z

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

What is the current behavior? (You can also link to an open issue here)

What is the new behavior (if this is a feature change)?

Does this PR introduce a breaking change?

Please check if the PR fulfills these requirements

The commit message follows our guidelines: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

Other information:

Closes #15351

petebacondarwin · 2016-11-16T10:40:52Z

I'm aware that Travis is not happy. I will fix this later today and maybe even break the changes into smaller commits for easier reviewing :-)

petebacondarwin · 2016-11-17T08:30:28Z

OK, smaller commits. Travis is happy.
What more could you want of a PR?

mgol · 2016-11-17T11:44:43Z

src/ngCookies/cookieStore.js

@@ -5,6 +5,8 @@ angular.module('ngCookies').
 * @ngdoc service
 * @name $cookieStore
 * @deprecated
+ * Please use the {@link ngCookies.$cookies `$cookies`} service instead.


Hasn't this been deprecated for some time now? Perhaps we should schedule a removal timeline?

It'd be also nice to mention the version in which this was deprecated.

Yes but not in this PR :-)

Narretz · 2016-11-17T16:23:08Z

docs/app/assets/css/docs.css

@@ -662,6 +662,12 @@ ul.events > li {
  max-width: 100%;
 }

+.deprecated-title {


Shouldn't this technically be part of the deprecation commit?

you're right, although I am not sure I have the energy for further rebasing :-/

Narretz · 2016-11-17T16:45:49Z

Good stuff. Having the templates in the repo allows us to move faste with changes, too.
A few notes:

I think using "warning" is a bit too weak for deprecation. It should be danger.
The API deprecation template is different. We should ideally use the same as for props and methods (can do in a follow-up)
In a follow-up, we should also make the deprecation notices in @description blocks consistent. Most noticable in the compile docs
Can we have "sub-annoations/tags" for @deprecated? then we could insert @since_version, @remove_version, and @description, and make this consistent across the board

mgol · 2016-11-17T17:11:43Z

Can we have "sub-annoations" for @deprecated? then we could insert @since_version, @remove_version, and @description, and make this consistent across the board

That would be wonderful.

gkalpak · 2016-11-17T20:28:45Z

docs/config/templates/ngdoc/api/module.template.html

+
+  {% code %}
+      <script src="angular.js">
+      <script src="{$ doc.packageFile $}">


Missing closing <script> tags.

gkalpak · 2016-11-17T20:33:36Z

docs/config/templates/ngdoc/api/module.template.html

-      <a href="http://bower.io">Bower</a> e.g.
-      {% code %}bower install {$ doc.packageName $}#X.Y.Z{% endcode %}
+      <a href="http://bower.io">Bower</a><br>
+      e.g. {% code %}bower install {$ doc.packageName $}@X.Y.Z{% endcode %}


Shouldn't this be # instead of @?

this is what is in dgeni-packages - so it looks like a breakage - but then it is re-fixed in a subsequent commit.

gkalpak · 2016-11-17T20:35:52Z

docs/config/templates/ngdoc/api/module.template.html

@@ -69,7 +61,6 @@ <h2 id="known-issues">Known Issues</h2>
 {% endif %}


-{% if doc.componentGroups.length %}


Why was this removed?

this is what is in dgeni-packages - so it looks like a breakage - but then it is re-fixed in a subsequent commit.

petebacondarwin · 2016-11-17T23:37:40Z

Can we have "sub-annoations" for @deprecated? then we could insert @since_version, @remove_version, and @description, and make this consistent across the board

The content of an annotation is completely configurable. But it can't really use sub-annotations, because the parser would see them as no top level annotations.
But you can do something like:

@deprecated since-version="..." remove-version="..." what is left is description

Then we would just parse for the attributes at the start of the description and pull them out.

Is that what you want?

petebacondarwin · 2016-11-17T23:51:53Z

Fixed up.

Narretz · 2016-11-18T00:32:55Z

@petebacondarwin Yes, this custom annoation content like you describe is what I'd like. I think @param does something like that? It has some custom transforms in the tag-defs. I was lead a bit in a wrong direction by looking a @method which seems to have "real" sub-annoations, but then again that's jsdoc, which is different.

petebacondarwin · 2016-11-18T10:47:19Z

OK, so I have updated the @deprecation tag to take sinceVersion and removeVersion options.

I also moved the docs.css file changes to the correct commit :-)

@Narretz PTAL

mgol · 2016-11-18T10:52:42Z

There are some linting violations but it's most likely due to us not checking docs properly. We can fix it later.

The new @deprecated syntax is not yet used, is it, @petebacondarwin?

mgol · 2016-11-18T11:01:08Z

The deprecation notice has disappeared from the ngComponentRouter page.

Closes angular#15351

Closes #15351 Closes #15394

Closes angular#15351 Closes angular#15394

Closes #15351 Closes #15394

Closes angular#15351 Closes angular#15394

petebacondarwin added branch: 1.6.x needs: review type: chore type: docs labels Nov 15, 2016

petebacondarwin added this to the 1.6.0-rc.1 milestone Nov 15, 2016

googlebot added the cla: yes label Nov 15, 2016

petebacondarwin force-pushed the deprecated-notices branch 2 times, most recently from 5f5acc4 to 08fce2d Compare November 16, 2016 16:37

mgol reviewed Nov 17, 2016

View reviewed changes

Narretz reviewed Nov 17, 2016

View reviewed changes

gkalpak approved these changes Nov 17, 2016

View reviewed changes

petebacondarwin force-pushed the deprecated-notices branch from 08fce2d to bd33823 Compare November 17, 2016 23:50

petebacondarwin force-pushed the deprecated-notices branch from bd33823 to 161f2e8 Compare November 18, 2016 10:46

petebacondarwin added 4 commits November 18, 2016 11:28

chore(package.json): update to latest dgeni-packages

752c989

chore(docs): bring in all templates from dgeni-packages

17e98ac

chore(docs): deprecation notices for methods and properties

35191fb

Closes angular#15351

docs(*): fix up deprecation notices

00ad1ec

petebacondarwin force-pushed the deprecated-notices branch from 113d257 to 00ad1ec Compare November 18, 2016 11:30

petebacondarwin closed this in f56926a Nov 18, 2016

petebacondarwin added a commit that referenced this pull request Nov 18, 2016

chore(docs): deprecation notices for methods and properties

6855c4f

Closes #15351 Closes #15394

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): deprecation notices for methods and properties

3f12bcd

Closes angular#15351 Closes angular#15394

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): deprecation notices for methods and properties

37e2335

Closes angular#15351 Closes angular#15394

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): deprecation notices for methods and properties

0014a28

Closes angular#15351 Closes angular#15394

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): deprecation notices for methods and properties

1d4a87a

Closes angular#15351 Closes angular#15394

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): deprecation notices for methods and properties

78eed8d

Closes angular#15351 Closes angular#15394

petebacondarwin added a commit that referenced this pull request Nov 23, 2016

chore(docs): deprecation notices for methods and properties

0532b42

Closes #15351 Closes #15394

petebacondarwin added a commit that referenced this pull request Nov 24, 2016

chore(docs): deprecation notices for methods and properties

d1bbc25

Closes #15351 Closes #15394

ellimist pushed a commit to ellimist/angular.js that referenced this pull request Mar 15, 2017

chore(docs): deprecation notices for methods and properties

656c87d

Closes angular#15351 Closes angular#15394

		@@ -69,7 +61,6 @@ <h2 id="known-issues">Known Issues</h2>
		{% endif %}


		{% if doc.componentGroups.length %}

chore(docs): deprecation notices for methods and properties #15394

chore(docs): deprecation notices for methods and properties #15394

Uh oh!

Conversation

petebacondarwin commented Nov 15, 2016

Uh oh!

petebacondarwin commented Nov 16, 2016

Uh oh!

petebacondarwin commented Nov 17, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Narretz commented Nov 17, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mgol commented Nov 17, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

petebacondarwin commented Nov 17, 2016

Uh oh!

petebacondarwin commented Nov 17, 2016

Uh oh!

Narretz commented Nov 18, 2016

Uh oh!

petebacondarwin commented Nov 18, 2016

Uh oh!

mgol commented Nov 18, 2016

Uh oh!

mgol commented Nov 18, 2016

Uh oh!

Uh oh!

Narretz commented Nov 17, 2016 •

edited

Loading